home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1995 November
/
EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso
/
earcd
/
patch
/
ppak25_1.lha
/
PhonePak_2.5
/
libsreq.library.readme
< prev
next >
Wrap
Text File
|
1994-05-18
|
12KB
|
290 lines
ReqLibrary, release 2.6
-------------------------
DATE Sat Mar 9 01:44:38 1991
The req.library is a run time re-entrant library that is designed
to make it easier for programmers to use powerful, easy to use
requesters for communicating with users. The requester library
includes such functions as a color requester, file requester, message
display requester and many functions to make the creation of gadgets
for your own custom requesters easier.
Req.library was written by Colin Fox (of Pyramyd Designs) and
Bruce Dawson (of CygnusSoft Software). Req.library is a freely
distributable library that may be used in commercial products without
paying any royalties. We encourage you to use the requester library
in all of your programs, to make them easier to write, and to use.
Req.library is not public domain. The requester library and all
documentation and example programs are all copyright 1989.
//////////////////////////////////////////////////////////////////////
Changes from req 2.5 to req 2.6
- You can now bring up the file requester from ARexx.
- Docs now in Autodoc format
- Bug fixed in font requester in Showoffreq
- es_SIZEOF changed to ess_SIZEOF in reqbase.i so it doesn't collide
with a new entry in intuition.i in 2.0
- Included spiffy new program: ReqMore! With source! This shows how
to use the RealTimeScroll() routine in req.library, and may also
serve as the basis of a tiny text editor for some enterprising programmer.
//////////////////////////////////////////////////////////////////////
Changes from req 2.4 to req 2.5
- It was pointed out to me that Showoffreq.c and reqglue.asm haven't been
updated in a while, so here they are, updated.
- This version includes updates for both Lattice reqglue and Aztec reqglue.
There are 4 reqglues-
lreqgluenb.o - for old Lattice or for Lattice compatable executables.
the nb is for No Base relative addressing
lreqglue.o - for new Lattice.
areqglue.o - old 3.6x Aztec
areqglue50d.o - New 5.0d Aztec
- I've also included the .fd file with this release, so if you wish to produce
a pragma file (or the equivalent), it's now easier.
//////////////////////////////////////////////////////////////////////
Changes from req 2.3 to req 2.4
- Since Commodore saw fit to use our FileRequester name for their structure,
I have to change it to 'struct ReqFileRequester{};'
- And just to forstall any further problems, I changed ScrollStruct to
ReqScrollStruct.
I know these are minor changes, but it had to be done.
//////////////////////////////////////////////////////////////////////
Changes from req 2.2 to req 2.3
- It was found that the definition of ReqBase was as a *Library, not
as a *ReqLib, which would preclude getting to the various handy
pointers. This was fixed.
- Tune-ups have been made to the reqbase.? include files.
//////////////////////////////////////////////////////////////////////
Changes from req 1.2 to req 2.2
- All requesters handle fonts properly under Workbench 2.0
- The TextRequest now has a timeout. You supply the length of time, in
seconds, and the requester will CANCEL itself after that time.
- The GetLong requester now displays the Minimum and Maximum values
on the window.
- Format() has been renamed ReqFormat(), since there is now a DOS routine
called Format() that does something significantly different.
- ReqFormat() now returns the length of the formatted string, and it is
now safe to pass a null result buffer. This is useful if you wish to
allocate space for a string without needing a buffer first. Just run
ReqFormat() on the string once without a result buffer, and it will tell
you how long the string is. Then allocate the memory and do it again
with the result buffer.
- For future compatability, you must now put REQVERSION in all Version
structure fields. This begins now, as the Timeout routine looks at
the version.
- RealTimeScroll now passes, as the 5th parameter (and in A0) the scroll
structure to ScrollAndDraw (your routine). This allows easier creation of
re-entrant code (you don't need to have a global pointer to the
scrollstruct).
- ARexx interface
Many thanks to Steve Lyons for writing the rexx module for req.library.
To hook req.library in as an ARexx function library, you must execute the
following line:
rxlib req.library -5 -60 2
For example, my rxlib settings read as such:
rxlib rexxmathlib.library 5 -30 0
rxlib rexxapclib.library 0 -30 0
rxlib rexxsupport.library -5 -30 0
rxlib rexxarplib.library -10 -30 0
rxlib req.library -5 -60 2
Steve also wrote the following 4 ARexx <-> Req bindings:
------------------------------------------------------------------------------
colourreq()
This function requires no parameters, but you CAN pass the default colour
if you like.
------------------------------------------------------------------------------
intreq("Title",min,max)
This function now displays the min and max values, so you know what's expected.
------------------------------------------------------------------------------
stringreq("Title","initial string",StringBufSize,VisibleSize)
The only manditory paramter is Title.
There is no default initial string, so it would be blank
StringBufSize defaults to 255
VisibleSize defaults to 40
------------------------------------------------------------------------------
textreq("Text body","Title","Cancel"," Ok ","Middle",timeout)
Something new for req.library 2.2 is timeouts. Right now the only requester
that has timeouts is TextRequest(), but they will be added to the others.
the timeout is in seconds. When the timeout expires, it returns FALSE.
The only required parameter is the "Text Body"
------------------------------------------------------------------------------
//////////////////////////////////////////////////////////////////////
Req.library is dedicated to the programmers who make the Amiga
shine the way it was meant to.
OverView:
All of the req.library functions that bring up requesters allow
you two ways of specifying what screen you would like the requester to
appear on. The first way is the more efficient way, because you only
have to set it up once and then it takes care of things automatially.
There is a field in all process structures called the pr_WindowPtr.
This pointer is used by DOS to decide where to put it's requesters.
If pr_WindowPtr contains a zero, requesters go on the workbench
screen. If it contains the address of a window, then requesters go on
that window's screen. If it contains a negative one, then no DOS
requesters come up. The req.library requesters all use this variable,
if they are called from a process . However, if the pointer is -1,
the req.library functions do still appear, on the workbench screen.
The second way was put in mainly so that the requesters can be
called from tasks. Since a task does not have a process structure, it
also lacks a pr_WindowPtr. Therefore, all of the requester functions
which can be used from a task (currently everything except the file
requester) can be passed a window pointer, either as a parameter or as
an element in a structure. Important: This pointer takes precedence
over the pr_WindowPtr so if you wish the requesters to use the
pr_WindowPtr you must zero the window fields that the routines are
expecting. In the case of fields in a structure this can be easy as
long as you make sure your structure defaults to being zero
everywhere.
Setting the pr_WindowPtr is quite a simple matter. All you have
to do is do a FindTask((char *)0); which returns a pointer to your own
task and your own process (a task structure is the first element of a
process structure). Then you simply preserve the old value of
pr_WindowPtr (VERY IMPORTANT!!!) and put a window pointer into it.
eg:
/* Find my task. */
myprocess = (struct Process *)FindTask((char *)0);
oldwindowptr = myprocess->pr_WindowPtr;
myprocess->pr_WindowPtr = window;
or:
MOVE.L 4,A6
MOVE.L #0,A1
SYS FindTask ;Find my task.
MOVE.L D0,_myprocess
MOVE.L D0,A0
MOVE.L pr_WindowPtr(A0),_oldwindowptr
MOVE.L _window,pr_WindowPtr(A0)
Before your program exits it is VERY important that it restore the
previous value of pr_WindowPtr. If you don't, then your program will
work in some situations, but will BLOW UP in others. For example, if
you execute (without using the 'run' command) a program, which then
sets the pr_WindowPtr to point at one of its windows and the exits
without restoring it, then the next time a DOS requester tries to
appear... BOOM! The machine will probably crash as DOS tries to open
a requester on a now closed screen. Therefore, before leaving:
myprocess->pr_WindowPtr = oldwindowptr;
or:
MOVE.L _myprocess,A0
MOVE.L _oldwindowptr,pr_WindowPtr(A0)
One final note. The pr_WindowPtr field exists in the process
structure. This means that a task does not have this field.
Therefore, if you want to call one of the requester library functions
from a task, you will not be able to specify what screen you would
like the requester to appear on by setting the pr_WindowPtr field.
All of the functions that open requesters and can be called from a
task (the file requester/font requester is the only one that can't be
called froma task) have some other way of specifying which screen you
would like them to open on. They will have either have a field in the
structure which you must pass them or a parameter which can contain a
window pointer to one of the windows on your custom screen. If this
pointer is non-zero then it overrides the pr_WindowPtr field.
By opening the requester library, you not only gain access to all
of the functions documented below, but to some other goodies as well.
Req.library needs and therefore opens several other libraries,
including dos.library, intuition.library, graphics.library and the
console device. All of these pointers are stored in the ReqLib
structure which you get a pointer to when you open the req.library.
Therefore, you can save yourself a little bit of code by grabbing
these fields after opening the requester library. The only thing to
beware of is don't use these values after you have close the requester
library, because at that point there is no guarantee that they will
still be valid.
In addition to these libraries, the Images pointer in the req
library structure points to a set of ten small images (four arrows and
six letters [R, G, B, H, S, V]) which have are guaranteed to be in
chip memory. These can be used if your program requires this type of
images.
One thing to keep in mind when using the gadget creation routines
is that there isn't any way for us to check that you have passed us a
pointer to the correct size of buffer, so you _must_ make sure that
you are allocating the right amount of memory.
The two glue files (lreqglue.o and areqglue.o) are for Lattice-C
(now SAS/C) and Aztec-C respectively. If you don't have direct
library access, simply link in the appropriate glue file to access the
library.
With the new version of Lattice (5+) you can now jump to library
routines directly, so there is no need for glue code. You can do this
with Aztec too, apparently, but I don't have the pragma maker for
Aztec.